Mask Aadhaar API

The following document highlights the details of the Mask Aadhaar API.

API Description

Objective

The Mask Aadhaar API hides the valid Aadhaar numbers and the associated QR (quick response) code in any document by blurring them for privacy and security reasons.

Input	Output
Images or files with the user's Aadhaar	The masked Aadhaar document

API URL

https://ind-ckyc.hyperverge.co/api/v1/maskAadhaar

API Endpoint

maskAadhaar

Overview

The Mask Aadhaar API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format, and you should upload all images and files as form-data through a POST request.

Method - POST

Authentication

You need a unique pair of application ID (appId) and application key (appKey) from HyperVerge to verify your identity for accessing the Mask Aadhaar API.

Headers

Header	Mandatory / Optional	Description	Input Format
content-type	Mandatory	Defines the media type for the request payload	multipart/form-data
appId	Mandatory	The application ID shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
transactionId	Mandatory	A unique identifier for tracking a user journey	This should be both unique and easily associated with the user's journey in your application(s)

Inputs

The following table provides the details of the parameters required for the Mask Aadhaar API's request body:

Parameter	Mandatory / Optional	Type	Description	Input Format	Default Value
file	Mandatory	file	Images or files to be masked	Multipart file upload	Not Applicable
maskStandardAadhaarOnly	Optional	string	If set to "yes", masks only the first 8 digits of the user's Aadhaar number	yes / no	no
maskFullAadhaar	Optional	string	If set to "yes", masks all 12 digits of the user's Aadhaar number	yes / no	no
maskQR	Optional	string	If set to "yes", masks the QR code associated with the user's Aadhaar	yes / no	yes
returnMaskingInfo	Optional	string	If set to "yes", the API returns the maskingInfo.masked field with the details of the masking result	yes / no	no
returnInputImage	Optional	string	If set to "yes", the API returns the input image as a URL that expires after 15 minutes	yes / no	no
maskAllAadhaarNumbers	Optional	string	If set to "yes", the API uses a more generic OCR to mask all Aadhaar numbers in the document	yes / no	no
flagNonAadhaarCards	Optional	string	Enhances non-Aadhaar document classification. Works only when maskAllAadhaarNumbers is set to "yes"	yes / no	no
checkPreMasked	Optional	string	If set to "yes", the API checks if the Aadhaar is already masked. Note Ensure that you enable the returnMaskingInfo parameter to retrieve the pre-masked information under the maskingInfo field of the response, if applicable.	yes / no	no

Request

The following code snippets demonstrate standard curl requests for the Mask Aadhaar API:

Request without QR Masking

curl --location --request POST 'https://ind-ckyc.hyperverge.co/api/v1/maskAadhaar' \
--header 'appId: <Enter_the_App_ID>' \
--header 'appKey: <Enter_the_App_Key>' \
--header 'transactionId: <Enter_the_Transaction_ID>' \
--form 'file=@"<Enter_the_File_Path>"'

Request with QR Masking

curl --location --request POST 'https://ind-ckyc.hyperverge.co/api/v1/maskAadhaar' \
--header 'appId: <Enter_the_App_ID>' \
--header 'appKey: <Enter_the_App_Key>' \
--header 'transactionId: <Enter_the_Transaction_ID>' \
--form 'file=@"<Enter_the_File_Path>"' \
--form 'maskQR="yes"'

Success Response

The following code snippet demonstrates a success response from the Mask Aadhaar API. It includes information about the document type, input file name, masked file name, occurrences of standard and non-standard Aadhaar numbers, masked file URL, total pages, and page-wise masked occurrences.

{
  "status": "success",
  "statusCode": "200",
  "result": {
    "docType": "<Doc_Type>",
    "inputFile": "<Input_File_Name>",
    "maskedFile": "<Masked_File_Name>",
    "maskedOccurrences": {
      "standardAadhaar": "<Standard_Aadhaar_Count>",
      "nonStandardAadhaar": "<Non_Standard_Aadhaar_Count>"
    },
    "maskedFileUrl": "<Masked_File_URL>",
    "totalPages": "<Total_Pages>",
    "pageDetails": [
      {
        "page": "<Page_Number>",
        "maskedOccurrences": {
          "standardAadhaar": "<Standard_Aadhaar_Count>",
          "nonStandardAadhaar": "<Non_Standard_Aadhaar_Count>"
        }
      }
    ]
  }
}

Success Response Details

The following table outlines the details of the success response from the Mask Aadhaar API:

Parameter	Type	Description
docType	string	The type of document detected. Possible values: STANDARD_AADHAAR:Detected a basic or standard Aadhaar NON_STANDARD_AADHAAR:Detected a non-standard or alternative format of Aadhaar NOT_AADHAAR:Detected a document that is not an Aadhaar NOT_SURE:The document type could not be identified
inputFile	string	The name of the input file submitted for masking
maskedFile	string	The name of the output masked file
maskedOccurrences	object	The count of standard and non-standard Aadhaar numbers masked in the document
maskedFileUrl	string	The URL of the masked file
totalPages	integer	The total number of pages in the submitted document
pageDetails	array	Page-wise breakdown of masking occurrences
maskingInfo.masked	string	The masking result. Returned only when returnMaskingInfo is set to "yes". Possible values: yes:The document was masked successfully pre_masked:The document is already masked not_sure:The masking was unsuccessful and the API failed to determine if the card was pre-masked

Error Responses

The following are some error responses from the Mask Aadhaar API:

Missing Input

{
  "status": "failure",
  "statusCode": "400",
  "error": {
    "code": "ER_FILE_NOT_FOUND",
    "message": "No file attached"
  }
}

Page Limit Exceeded

{
  "status": "failure",
  "statusCode": "400",
  "error": {
    "code": "ER_PAGE",
    "message": "pages exceeded the supported length of 5"
  }
}

Missing/Invalid Credentials

{
  "status": "failure",
  "statusCode": "401",
  "error": "Missing/Invalid credentials"
}

File Size Error

{
  "status": "failure",
  "statusCode": "413",
  "error": {
    "code": "ER_SERVER",
    "message": "File too large"
  }
}

Internal Server Error

{
  "status": "failure",
  "statusCode": "500",
  "error": {
    "code": "ER_SERVER",
    "message": "Internal Server Error"
  }
}

Error Response Details

A failure or error response contains a failure status with a relevant status code and error message. The following table lists the error responses for the Mask Aadhaar API:

Status Code	Error Message	Error Description	Error Resolution
400	No file attached	The request is missing the file containing the user's Aadhaar	Attach the required file to the request
400	pages exceeded the supported length of 5	The API supports input files up to five pages in length	Reduce the document to 5 pages or fewer before submitting
401	Missing/Invalid credentials	The request is missing the mandatory appId and appKey combination or has invalid values	Verify and provide valid credentials
413	File too large	The submitted file size exceeds the maximum allowed limit	Reduce the file size before submitting
500	Internal Server Error	Kindly check the request headers or contact the HyperVerge team for resolution	Check the request headers or contact the HyperVerge team for resolution